API Standard Documentation

1. Document Information

Document Name: SERVICEME System API Standard Documentation
Version: v1.0
Release Date: 2025-07-18
Scope: Applicable to enterprise intelligent scenarios, supporting functions such as identity authentication, knowledge Q&A, process automation, data analysis, and content generation. The API adopts a standard RESTful architecture, facilitating system integration and cross-platform applications. It is widely used in business modules such as customer service, marketing, finance, and human resources, enhancing collaboration efficiency and intelligent decision-making capabilities.

2. Revision History

Version	Revision Date	Revision Content
v1.0	2025-07-18	Initial draft

3. Overview

3.1 Purpose of the Document

State the objective of the document, for example:

This document defines the API specifications for the SERVICEME system, including request format, response format, error codes, etc., for reference by callers.

3.2 Terms and Abbreviations

API: Application Programming Interface
HTTP: HyperText Transfer Protocol
JSON: JavaScript Object Notation
RESTful: An API design style

3.3 API Design Principles

Follow RESTful style (where applicable).
Use HTTPS protocol to ensure security.
Data format is unified as JSON.
API version management (e.g., /v1/xxx).

4. General Specifications

4.1 Request Specifications

Request Methods: GET/POST/PUT/DELETE, etc.
Request Headers:
- Content-Type: application/json
- Authorization: Bearer {token} (if authentication is required).
Request Parameters:
- Query parameters (GET), Body parameters (POST/PUT).
- Description of required/optional fields.

4.2 Response Specifications

Response Format:

{
  "code": 200,       // Status code
  "message": "成功",  // Description
  "data": {}         // Returned data (optional)
}

HTTP Status Codes:
- 200: Success
- 400: Bad request parameters
- 401: Unauthorized
- 500: Internal server error

4.3 Error Code Table

Error Code	Meaning	Suggested Solution
200	Success	-
422	Parameter error	-
40001	Missing parameter	Check required fields
50001	Internal server error	Contact administrator

5. API Details

5.1 API 1: Get User Information

API Path: GET /lite_api/v1/iam/user/{user_id}
Request Parameters:

Parameter Name Type Required Description
userId Path Yes User ID

Parameter Name	Type	Required	Description
userId	Path	Yes	User ID

Request Example:

GET /v1/iam/user/293456 HTTP/1.1
Authorization: Bearer abcdef123456

Response Example:

{
    "code": 200,
    "data": {
        "username": "string",
        "email": "string",
        "real_name": "",
        "nickname": "",
        "is_superuser": false,
        "avatar": "",
        "enable": true,
        "id": "string",
        "is_aad": false,
        "serial_number": "string",
        "created_at": "2019-08-24T14:15:22.123Z",
        "updated_at": "2019-08-24T14:15:22.123Z",
        "last_login": "2019-08-24T14:15:22.123Z",
        "roles": [],
        "user_roles": [],
        "organizations": [],
        "gender": 0,
        "birthday": "2019-08-24T14:15:22.123Z",
        "wechat": "string",
        "region": "string",
        "time_difference": 0,
        "join_time": "2019-08-24T14:15:22.123Z",
        "office_phone": "string",
        "mobile_phone": "string",
        "description": "string"
    },
    "message": "success"
}

5.2 API 2: Create User

API Path: POST /lite_api/v1/iam/user/
Request Parameters:

Parameter Name Type Required Description
username string Yes Username
email string No Email
real_name string No Real name

Parameter Name	Type	Required	Description
username	string	Yes	Username
email	string	No	Email
real_name	string	No	Real name

Request Example:

{
    "username": "string",
    "email": "",
    "real_name": "",
}

Response Example:

{
    "username": "string",
    "email": "string",
    "real_name": "",
}

5.3 API 3: Create Agent

API Path: POST /lite_api/v1/robots/

Request Parameters:

Parameter Name	Type	Required	Description
info	object	Yes	Agent info and name
masks	array	No	Agent masks
knowledge_bases	array	No	Knowledge bases
skills	array	No	Skills
mcps	array	No	Data models
data_sources	array	No	Data sources
keywords_filter	object	No	Keyword filter
feedback_accounts	array	No	Feedback accounts

Request Example:

{
    "info": {
        "name": "string",
        "weight": 0,
        "avatar_url": "string",
        "description": "",
        "prompt": "string",
        "prologue": "string",
        "robot_type": "",
        "flow_id": "ef710584-0706-4b4b-b481-dd44a4541137",
        "cluster_group_id": "921cd751-fc17-4b9d-a7ec-91a434beaf0a",
        "product_position": "chat-x",
        "chat_rounds": 0,
        "user_id": "string",
        "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
        "split_type": "string",
        "load_type": "string",
        "spliter_json": "string",
        "embedding_id": "18e0b745-2b45-46cb-a826-bc9049d1152c",
        "user_skill_auths": [
            null
        ],
        "need_summary": true,
        "force_execute": true,
        "open_filter": true,
        "record_chat": true,
        "is_published": true,
        "category_ids": [
            "497f6eca-6276-4993-bfeb-53cbbbba6f08"
        ],
        "recommend_question": false,
        "feedback": false,
        "knowledge_config": {
            "search_mode": "hybrid",
            "k": 5,
            "doc_score": 0.7,
            "qa_score": 0.8,
            "metadata": "none",
            "show_reference": false
        },
        "editable": true,
        "question_guide": false,
        "operator_execute": false,
        "bi_config": {
            "query_rewrite": false,
            "divide_think": false
        }
    },
    "masks": [
        {
            "mask_set_id": "d0bee2ed-0859-4bb6-8598-f64d47a5a28b"
        }
    ],
    "knowledge_bases": [
        {
            "classification_id": "string",
            "classification_name": "string",
            "classification_icon": "string",
            "workspaces": []
        }
    ],
    "skills": [
        {
            "skill_group_id": "85161907-67ae-4ae2-8fee-99b7d6fcc3f8"
        }
    ],
    "mcps": [],
    "data_sources": [
        {
            "skill_group_id": "85161907-67ae-4ae2-8fee-99b7d6fcc3f8"
        }
    ],
    "keywords_filter": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "robot_id": "8fe44936-b905-428b-ace5-566f232fcce8",
        "key_words": [
            "string"
        ],
        "review_input": true,
        "preset_reply_input": "string",
        "review_output": true,
        "preset_reply_output": "string"
    },
    "feedback_accounts": []
}

Response Example

{
    "code": 200,
    "data": null,
    "message": "success"
}

5.4 API 4: Get Agent

API Path: POST /lite_api/v1/robots/{robot_id}
Request Parameters:

Parameter Name	Type	Required	Description
robot_id	string	Yes	Agent ID
internal_use	boolean	No	Internal use only

Request Example:

GET /lite_api/v1/robots/00001 HTTP/1.1
Authorization: Bearer abcdef123456

Response Example:

{
    "code": 200,
    "data": {
        "info": {
            "name": "string",
            "weight": 0,
            "avatar_url": "string",
            "description": "",
            "prompt": "string",
            "prologue": "string",
            "robot_type": "",
            "flow_id": "ef710584-0706-4b4b-b481-dd44a4541137",
            "cluster_group_id": "921cd751-fc17-4b9d-a7ec-91a434beaf0a",
            "product_position": "chat-x",
            "chat_rounds": 0,
            "user_id": "string",
            "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
            "split_type": "string",
            "load_type": "string",
            "spliter_json": "string",
            "embedding_id": "18e0b745-2b45-46cb-a826-bc9049d1152c",
            "user_skill_auths": [
                null
            ],
            "need_summary": true,
            "force_execute": true,
            "open_filter": true,
            "record_chat": true,
            "is_published": true,
            "category_ids": [
                "497f6eca-6276-4993-bfeb-53cbbbba6f08"
            ],
            "recommend_question": false,
            "feedback": false,
            "knowledge_config": {
                "search_mode": "hybrid",
                "k": 5,
                "doc_score": 0.7,
                "qa_score": 0.8,
                "metadata": "none",
                "show_reference": false
            },
            "editable": true,
            "question_guide": false,
            "operator_execute": false,
            "bi_config": {
                "query_rewrite": false,
                "divide_think": false
            },
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "manageable": false
        },
        "masks": [],
        "knowledge_bases": [],
        "skills": [],
        "mcps": [],
        "data_sources": [],
        "keywords_filter": {
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "robot_id": "8fe44936-b905-428b-ace5-566f232fcce8",
            "key_words": [
                "string"
            ],
            "review_input": true,
            "preset_reply_input": "string",
            "review_output": true,
            "preset_reply_output": "string"
        },
        "feedback_accounts": []
    },
    "message": "success"
}

5.5 API 5: Upload File

API Path: POST /Api/Workspace/File/UploadFiles
Request Parameters:

Parameter Name	Type	Required	Description
Files	array	No	Files to be uploaded
WorkspaceId	string	No	string
FullPath	string	No	Full path to upload the file
IsCover	boolean	No	Is system upload
UserId	integer	No	User id (for public API)
UserEmail	string	No	User email (for public API)
OCRMode	string	No	OCR mode

Response Example:

{
    "success": true,
    "msg": "string",
    "data": [
        {
            "workspaceId": 0,
            "fullName": "string",
            "id": 0
        }
    ]
}

6. Security Specifications

Authentication Methods: OAuth2.0/JWT/API Key.
Data Encryption: Sensitive fields must be transmitted encrypted (e.g., passwords).

Rate Limiting Policy: API call frequency limits are as follows.

Scenario	Common Limit	Description
Open API (e.g., 3rd party)	10~100 times/minute	For example, WeChat Pay, Alipay open APIs usually limit 50~200 times/minute (depending on API level).
Internal System API	100~1000 times/minute	Internal service calls can be relaxed, but avoid excessive resource usage by a single service.
User Behavior API	5~60 times/minute	For sensitive operations such as login, SMS sending, etc., strict limits are required (e.g., SMS verification code API is usually limited to 1 time/60 seconds).
Data Query API	100~5000 times/minute	High-frequency query APIs can be appropriately relaxed, but caching should be used to reduce database pressure.
High-Concurrency Core API	Dynamic rate limiting (e.g., token bucket algorithm)	For example, e-commerce flash sale APIs may combine circuit breaker mechanisms and elastic scaling.

1. Document Information​

2. Revision History​

3. Overview​

3.1 Purpose of the Document​

3.2 Terms and Abbreviations​

3.3 API Design Principles​

4. General Specifications​

4.1 Request Specifications​

4.2 Response Specifications​

4.3 Error Code Table​

5. API Details​

5.1 API 1: Get User Information​

5.2 API 2: Create User​

5.3 API 3: Create Agent​

5.4 API 4: Get Agent​

5.5 API 5: Upload File​

6. Security Specifications​

1. Document Information

2. Revision History

3. Overview

3.1 Purpose of the Document

3.2 Terms and Abbreviations

3.3 API Design Principles

4. General Specifications

4.1 Request Specifications

4.2 Response Specifications

4.3 Error Code Table

5. API Details

5.1 API 1: Get User Information

5.2 API 2: Create User

5.3 API 3: Create Agent

5.4 API 4: Get Agent

5.5 API 5: Upload File

6. Security Specifications